Appendix A: Functions

The following is a list of all available functions and a complete description of each. For general information on how the External functions work and how you can use them in your calculations, please see the How to use Plug-ins PDF Document available on the CNS Plug-ins website.


CNSImage_Convert

Title
CNSImage_Convert
Format
CNSImage_Convert( Image ; Type {; Width {; Height {; Resolution {; Depth {; Quality {; TargetSize }}}}}} )
Data Type Returned
Image
Description
The CNSImage_Convert function allows you to convert an image. You can change the type of the image as well as the width, height, resolution, and depth. If your target image type is JPEG or TIFF, you can set the Quality. If your target image type is JPEG, you can set the targetsize.

For a list of image types, see "Reference: Image Types".
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Convert.
  • Type - The Type of the new Image. (Specify "" to keep the current Image Type. Types include: JPEG, GIF, PNG, BMP, EPS, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, and PDF.)
Parameters (Optional)
  • Width - The Width in pixels of the new Image. (Specify "" to keep the current Width.)
  • Height - The Height in pixels of the new Image. (Specify "" to keep the current Height.)
  • Resolution - The Resolution in pixels per inch of the new Image. (Specify "" to keep the current Resolution.)
  • Depth - The Bit-Depth of the new Image. (All settings may not work for all Image Types; Specify "" to keep the current Bit-Depth. Depths include: 1, 2, 4, 8, 16, 24, 32, -, 33, 34, 36, and 40.)
  • Quality - The Quality of the new Image. (Only available for JPEGs and TIFFs; Specify "" to keep the current Quality. You can also specify a number or keyword: min = 0, low = 256, normal = 512, high = 768, max = 1023, lossless = 1024.)
  • TargetSize - The Target File Size of the new Image. (Only available for JPEGs.)
Example
CNSImage_Convert( MyImage ; "JPEG" ; 100 ; 100 ; 72 ; 32 ; 1024 )
-> Returns a JPEG image 100 pixels wide with a resolution of 72, a depth of 32, and quality of 1024.

CNSImage_Convert( MyImage ; "PNGf" ; 100 ; 100 ; 72 )
-> Returns a PNG image 100 pixels wide with a resolution of 72.
Related
Reference: Image Types

CNSImage_Copy

Title
CNSImage_Copy
Format
CNSImage_Copy( Image )
Data Type Returned
Image
Description
This function is used in conjunction with the CNSImage_Import function to make a copy of the original image in case you need to populate the container field if the user cancels. Its use is limited to working around a bug in 7.0v3 and before when copying a container into itself.
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Copy
Example
CNSImage_Copy( Importing::original )
-> Returns a copy of the image in the "Importing::original" container field

CNSImage_Crop

Title
CNSImage_Crop
Format
CNSImage_Crop( Image ; Top ; Left ; Bottom ; Right )
Data Type Returned
Image
Description
The CNSImage_Crop function allows you to create a new image based on part of an image. In other words, it takes an image, crops it to your specifications and then returns it to you.
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Crop.
  • Top ; Left - The pixel coordinates of the Top, Left corner of the Crop rectangle.
  • Bottom ; Right - The pixel coordinates of the Bottom, Right corner of the Crop rectangle.
Example
CNSImage_Crop( MyImage ; 0 ; 0 ; 100 ; 100 )
-> Returns a 100 square pixel area from the image in the "MyImage" container.

CNSImage_Export

Title
CNSImage_Export
Format
CNSImage_Export( Image {; Path {; Prompt {; AllowConvert {; TypeList }}}} )
Data Type Returned
String
Description
This function allows you to save an image to any folder with any name. You can also export an image using a dialog. The function will return a string indicating the success or failure of the operation.
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Export.
Parameters (Optional)
  • Path - The Path and File Name the Image will be Exported to. (Specify "" or omit File Name to display Save File Dialog).
  • Prompt - A message to be displayed in the Save File Dialog.
  • AllowConvert - If True, this allows you to select an alternate File Type to Convert to as you Export. (Only available if the Save File Dialog is displayed.)
  • TypeList - A comma or semicolon-delimited list of Image File Types the user is Allowed to Convert to. (Valid Types are: JPEG, GIF, PNG, BMP, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, PDF)
Example
CNSImage_Export( Image )
-> Displays a save file dialog. You can edit the name of the file and navigate in the file dialog prior to saving.

CNSImage_Export( Image ; "/Drive/folder/filename.jpg" )
-> Saves an image to the folder "/Drive/folder/" with the name "filename.jpg".

CNSImage_Export( Image ; "Drive/folder/" )
-> Displays a save file dialog starting in the folder "Drive/folder/". You can edit the name of the file in the file dialog prior to saving.

CNSImage_Export( Image ; "" ; "Please locate where you would like to save this image." )
-> Displays a save file dialog with the prompt: "Please locate where you would like to save this image." . You can edit the name of the file in the file dialog prior to saving.

CNSImage_Export( Image ; "Drive/folder/" ; "" ; True )
-> Displays a save file dialog starting in the folder "Drive/folder/". You can edit the name of the file in the file dialog prior to saving and specify a different image format for the file to convert the image if you want.

CNSImage_File_GetPathToDB

Title
CNSImage_File_GetPathToDB
Format
CNSImage_File_GetPathToDB
Data Type Returned
String
Description
This function will return the Hard Drive Path to the Folder containting the Front-most Database in FileMaker. This is similar to FileMaker's own Get(FilePath) function, but returns the Path in a nicer format, plus it doesn't include the Database File Name. If the front-most database is a hosted database, this function will return an error.
Example
CNSImage_File_GetPathToDB
-> Returns a path to the folder containing the front-most database in FileMaker.

CNSImage_File_GetPathToFM

Title
CNSImage_File_GetPathToFM
Format
CNSImage_File_GetPathToFM
Data Type Returned
String
Description
This function will return the Hard Drive Path to the Folder containing the currently running FileMaker Application, be it FileMaker Pro, FileMaker Server, Web Publishing Engine, or a FileMaker Runtime.
Example
CNSImage_File_GetPathToFM
-> Returns the path to the folder containting the running FileMaker application.

CNSImage_File_SelectFileWithDialog

Title
CNSImage_File_SelectFileWithDialog
Format
CNSImage_File_SelectFileWithDialog{( StartPath {; TypeList {; Prompt }} )}
Data Type Returned
String
Description
The CNSImage_File_SelectFileWithDialog function allows you to use a dialog to locate a file on your hard drive and returns the path of the chosen file. You can specify the starting folder by specifying the optional "StartPath" param. You can limit the type of files to choose from by using the optional "TypeList" param. You can also display a message in the dialog by using the optional "Prompt" param.
Parameters (Optional)
  • StartPath - The Path to the Folder to display when the dialog first opens.
  • TypeList - A comma or semicolon-delimited list of Image File Types the user is allowed to Choose. For a complete list of types, view the "Reference: Image Types" section of the Function Reference.
  • Prompt - An optional Prompt or Message to display on the dialog.
Example
CNSImage_File_SelectFileWithDialog
-> A dialog is shown to choose a file.

CNSImage_File_SelectFileWithDialog( "~/Desktop/" )
-> A dialog is shown with the current user's Desktop as the starting folder.

CNSImage_File_SelectFileWithDialog( "" ; "JPG, PNG" )
-> A dialog is shown to choose a file limited to JPG and PNG image types.

CNSImage_File_SelectFileWithDialog( "" ; "JPG" ; "Please choose a JPG image:" )
-> A dialog is shown to choose a file limited to JPG images with the prompt: "Please choose a JPG image:".

CNSImage_File_SelectFileWithDialog( "" ; "" ; "Choose any image...." )
-> A dialog is shown to choose any type of image with the prompt: "Choose any image...".
Related
CNSImage_File_SelectFolderWithDialog

CNSImage_File_SelectFolderWithDialog

Title
CNSImage_File_SelectFolderWithDialog
Format
CNSImage_File_SelectFolderWithDialog{( StartPath {; Prompt } )}
Data Type Returned
String
Description
You can use this function to choose a folder using a dialog box. You can use the optional "StartPath" param to specify which folder to display when the dialog first opens. You can use the optional "Prompt" param to display a message in the dialog box.
Parameters (Optional)
  • StartPath - The Path to the Folder to display when the dialog first opens.
  • Prompt - An optional Prompt or Message to display on the Dialog.
Example
CNSImage_File_SelectFolderWithDialog
-> Displays a dialog so you can choose folder. The chosen path is returned.

CNSImage_File_SelectFolderWithDialog( "/" )
-> Displays a dialog so you can choose a folder, starting with the startup volume or first drive.

CNSImage_File_SelectFolderWithDialog( "Please choose a folder:" )
-> Displays a dialog so you can choose folder with the prompt: "Please choose a folder". The chosen path is returned.
Related
CNSImage_File_SelectFileWithDialog

CNSImage_Filter

Title
CNSImage_Filter
Format
CNSImage_Filter( Image )
Data Type Returned
Image
Description
With this function, you can apply a QuickTime filter to an image. QuickTime comes with several built-in filters such as Brightness, ColorSync, HSL Balance, RGB Balance, Blur, Edge Detection, Emboss, Sharpen, Color Style, Color Tint, and more. There are also third party filters available on the net.
Parameters (Required)
  • Image - The Container that contains the Image you want to Filter.
Example
CNSImage_Filter( MyImage )
-> Opens the filter dialog, and returns the filtered image after you have made your selection.

CNSImage_GetFromURL

Title
CNSImage_GetFromURL
Format
CNSImage_GetFromURL( URL )
Data Type Returned
Image
Description
You can download an image on the internet with this function. You can download fun images such as webcams, daily cartoons, or photos of the sun. You can also post new graphics for your solution to be downloaded across the net. Imagine if your database could check for new interface files on the net as part of your startup routine. Stop imagining, this is reality!
Parameters (Required)
  • URL - The full URL of the Image to Get.
Example
CNSImage_GetFromURL( "http://www.cnsplug-ins.com/graphics/CNS_mini_logo.jpg" )
-> Returns the "CNS_mini_logo.jpg" JPEG at the address "http://www.cnsplug-ins.com/graphics/CNS_mini_logo.jpg"

CNSImage_GetInfo

Title
CNSImage_GetInfo
Format
CNSImage_GetInfo( Image {; Field } )
Data Type Returned
String
Description
The CNSImage_GetInfo function returns information about an image such as the format, width, height, resolution, depth, quality, and size. You can also using the "Item" parameter to retrieve a specific value such as the width of an image.
Parameters (Required)
  • Image - The Container that contains the Image you need the Info of.
Parameters (Optional)
  • Field - A specific Info Item you need. (If this parameter is not defined, all Info Items will be returned. You can specify multiple fields separated by a semicolon. Fields: type, width, height, hres, vres, depth, quality, filesize, displaywidth, displayheight, layers, pathname, filename, and storage. )
Example
CNSImage_GetInfo( MyImage )
-> Returns a return delimited string of information for the image in the "MyImage" container.

CNSImage_GetInfo( MyImage ; "width" )
-> Returns the width of the image in the "MyImage" container.

CNSImage_GetInfo( MyImage ; "height;width" )
-> Returns the height and width separated by a return.

CNSImage_Import

Title
CNSImage_Import
Format
CNSImage_Import{( Path {; TypeList {; Prompt }} )}
Data Type Returned
Image
Description
The CNSImage_Import function allows you to easily import images into FileMaker. You can import by specifying a path to an image as well as using a dialog box to navigate to a desired image.
Parameters (Optional)
  • Path - The Path and File Name of the Image to Import. (Specify "" or omit File Name to display Open File Dialog).
  • TypeList - A comma or semicolon-delimited list of Image File Types the user is allowed to Import. Types include: JPEG, GIF, PNG, BMP, EPS, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, and PDF.
  • Prompt - A message to be displayed in the Open File Dialog.
Example
CNSImage_Import
-> A dialog is shown to choose an image.

CNSImage_Import( "/drive/folder/")
-> A dialog is shown to choose a file starting at the folder "/drive/folder/"

CNSImage_Import( "" ; "JPG, PNG" )
-> A dialog is shown to choose a file limited to JPG and PNG image types.

CNSImage_Import( "" ; "JPG" ; "Please choose a JPG image:" )
-> A dialog is shown to choose a file limited to JPG images with the prompt: "Please choose a JPG image:".

CNSImage_Import( "" ; "" ; "Choose any image...." )
-> A dialog is shown to choose any type of image with the prompt: "Choose any image...".

CNSImage_Reflect

Title
CNSImage_Reflect
Format
CNSImage_Reflect( Image; Direction )
Data Type Returned
Image
Parameters (Required)
  • Image - The Container that contains the Image you want to Reflect.
  • Direction - The Direction to Reflect the Image. (Specify X or H for Horizontal, Y or V for Vertical, or B or L for Both Horizontal and Vertical.)
Example
CNSImage_Reflect( Image; "H" )
-> Reflects the image in the "Image" container field horizontally.

CNSImage_Register

Title
CNSImage_Register
Format
CNSImage_Register( FirstName ; LastName ; RegNumber {; Option } )
Data Type Returned
String
Description
You can use this function to register a plug-in without having to use a dialog box. If you use the "Option" parameter, you can register via a dialog box using the "Dialog" value. You can also use value "Check" to test to see if the plug-in is registered or not. Finally, you can use the value "I Accept the License Agreement" to automatically accept the License Agreement dialog.
Parameters (Required)
  • First_Name - The Registration First Name you specified when you ordered. (See your Receipt.)
  • Last_Name - The Registration Last Name you specified when you ordered. (See your Receipt.)
  • Reg_Number - The Registration Number from your Receipt.
Parameters (Optional)
  • Option - Specify "Dialog" to enter your Registration Information in a Pop Up Dialog. (You can also specify "Dialog" as the FirstName parameter.) Specify "Check" to see if the plug-in is already Registered. (You can also specify "Check" as the FirstName parameter.) Specify "I Accept the License Agreement" to automatically accept the License Agreement dialog.

CNSImage_Rotate

Title
CNSImage_Rotate
Format
CNSImage_Rotate( Image ; Degrees )
Data Type Returned
Image
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Rotate.
  • Degrees - The Amount in Degrees that you want to Rotate the Image.
Example
CNSImage_Rotate( Image ; 45 )
-> Rotates the image in the "Image" field 45 degrees.

CNSImage_Transform

Title
CNSImage_Transform
Format
CNSImage_Transform( Image ; X1 ; Y1 ; X2 ; Y2 ; X3 ; Y3 ; X4 ; Y4 )
Data Type Returned
Image
Parameters (Required)
  • Image - A Container field that contains an Image or a Path and File Name to an Image you want to Transform.
  • X1 ; Y1 - The pixel coordinates of the Top, Left corner of the Transformation Rectangle.
  • X2 ; Y2 - The pixel coordinates of the Top, Right corner of the Transformation Rectangle.
  • X3 ; Y3 - The pixel coordinates of the Bottom, Right corner of the Transformation Rectangle.
  • X4 ; Y4 - The pixel coordinates of the Bottom, Left corner of the Transformation Rectangle.
Example
CNSImage_Transform( Image ; 0 ; 0 ; 200 ; 0 ; 200 ; 500 ; 0 ; 500 )
-> Transforms the image in the "Image" field. (Depending on the image, this would likely squish the image horizontally. For an example of this function in action, view the "Transform" example.)

CNSImage_Version

Title
CNSImage_Version
Format
CNSImage_Version{( Option )}
Data Type Returned
String
Parameters (Optional)
  • Option - You can use the following options: Specify "Auto Update" to return a more Auto Update friendly Version number, Specify "Configure" to bring up the "CNS Image" Configuration Dialog, Specify "About" to bring up the "CNS Image" Configuration Dialog with the About Tab as the first tab shown.
Example
CNSImage_Version
-> Returns the version number.

CNSImage_Version( "About" )
-> Brings up the "CNS Image" Configuration Dialog with the About Tab as the first tab shown.

CNSImage_Version( "Configure" )
-> Brings up the "CNS Image" Configuration Dialog

CNSImage_Version( "Auto Update" )
-> Specify "Auto Update" to return a more Auto Update friendly Version number

Reference: Image Types

Title
Reference: Image Types
Description
CNS Image uses the QuickTime libraries to import, export, and convert your images. QuickTime does not support all image formats for all operations. Below is a break down of what can be imported, exported, and converted.

Image Formats that can be Imported, or Converted From, on Both Mac OS X and Windows:

Image Name File Type File Extensions
JPEG JPEG .jpg; .jpeg; .jfif; .jpe
GIF GIFf .gif
PNG PNGf .png
Windows Bitmap BMPf .bmp
Macintosh PICT PICT .pct; .pict; .pic
TIFF TIFF .tif; .tiff
Photoshop 8BPS .psd
QuickTime Image qtif .qif; .qti; .qtif; .qt
Silicon Graphics .SGI .sgi
Targa TPIC .tga; .tpic
MacPaint PNTG .mac

Image Formats that can be Imported, or Converted From, only on Mac OS X:

Image Name File Type File Extensions
PDF PDF .pdf


Image Formats that can be Exported, or Converted To, on Both Mac OS X and Windows:

Image Name File Type File Extensions
JPEG JPEG .jpg; .jpeg; .jfif; .jpe
PNG PNGf .png
Windows Bitmap BMPf .bmp
TIFF TIFF .tif; .tiff
Photoshop 8BPS .psd
QuickTime Image qtif .qif; .qti; .qtif; .qt
Silicon Graphics .SGI .sgi
Targa TPIC .tga
MacPaint PNTG .mac


Notes:

- You can use either the Image Name or the File Type when specifying types in CNS Image.

- On Mac OS X, CNS Image uses both the File Type and the File Extensions in the Import Dialog to determine if a file is a valid image type. On Windows, CNS Image only uses the File Extensions in the Import Dialog. When exporting images from your database, CNS Image will append the first listed file extension to the file name.

- When using the CNSImage_Convert function, GIF images will be auto-converted to PNG images unless you specify another supported image type. PDF images will be auto-converted to JPEG images. When using the CNSImage_GetFromURL function, GIF images will automatically be converted to PNG images.

- QuickTime does not have support for Importing or Exporting EPS images, so CNS Image will be unable to work with any "by reference" EPS images. This also means that CNSImage_Import will not be able to import EPS images. However, if FileMaker is used to Import (and store) an EPS image, CNS Image can manipulate the "JPEG Preview" stored in the container.

- On Windows, if you paste an image into a container, the underlying format is a Windows MetaFile, DIB, or OLE format, which is incompatible with QuickTime. CNS Image will be able to manipulate the "JPEG Preview" though.



Reference: Paths

Title
Reference: Paths
Description
You can use the following path types in order to reference images in CNS Image functions:

imagemac:/HDName/folder/file.ext
imagewin:/C:/folder/file.ext
image:/POSIXpath/
/Volumes/VolumeName/Folder/file.ext
c:\folder\file.ext
VolumeName:Folder:file.ext
/C/Folder/file.ext
~/Desktop/file.ext